Mit DocuGenerate können Sie PDF- und Word-Dokumente direkt aus Ihrer Python-Anwendung erstellen. Diese Anleitung zeigt, wie Sie jede API-Methode ab Python 3.9 aufrufen. Die vollständige Liste der Parameter und Antworten finden Sie in der API-Referenz.
1. Authentifizierung
2. Vorlage erstellen
3. Vorlagen auflisten
4. Vorlage abrufen
5. Vorlage aktualisieren
6. Vorlage löschen
7. Dokument generieren
8. Dokumente auflisten
9. Dokument abrufen
10. Dokument aktualisieren
11. Dokument löschen
Jede Anfrage wird authentifiziert, indem Sie Ihren API-Schlüssel im Header Authorization senden. Speichern Sie den Schlüssel in einer Umgebungsvariable, statt ihn fest in Ihren Quellcode zu schreiben, und installieren Sie die Bibliothek requests, falls sie noch nicht verfügbar ist:
export DOCUGENERATE_API_KEY="YOUR-API-KEY"
pip install requests
Alle folgenden Beispiele verwenden diese Importe und Konstanten. Da requests bei HTTP-Fehlerstatus keine Ausnahme auslöst, prüft jedes Beispiel response.ok, bevor es die Antwort liest:
import os
import requests
API_URL = 'https://api.docugenerate.com/v1'
API_KEY = os.environ['DOCUGENERATE_API_KEY']
Wenn Ihr Konto Daten in einer anderen Region speichert, ersetzen Sie die Basis-URL durch den passenden regionalen Endpunkt, zum Beispiel https://api.eu.docugenerate.com/v1.
Um eine Vorlage zu erstellen, laden Sie die Vorlagendatei mit einer Anfrage an POST /template hoch. Dieser Endpunkt erfordert den Inhaltstyp multipart/form-data, den requests zusammen mit der Multipart-Boundary automatisch setzt, wenn die Datei in files übergeben wird:
with open('Business Letter.docx', 'rb') as file:
response = requests.post(
f'{API_URL}/template',
headers={
'Authorization': API_KEY,
'Accept': 'application/json'
},
files={'file': file},
data={'name': 'Business Letter'}
)
if not response.ok:
raise Exception(f'DocuGenerate API error {response.status_code}: {response.text}')
template = response.json()
print(template['id'])
Setzen Sie den Header Content-Type nicht selbst, sonst fehlt die Boundary und die Anfrage schlägt fehl. Die Antwort enthält die neue Vorlage, einschließlich der automatisch in der Datei erkannten tags:
{
"enhanced_syntax": false,
"versioning_enabled": false,
"folder": [],
"tags": {
"valid": [
"Date",
"Name",
"Job Title",
"Company Name",
"Street Address",
"City",
"State",
"Zip Code",
"Email",
"Phone"
],
"invalid": []
},
"created": 1791055374301,
"updated": 1791055374301,
"name": "Business Letter",
"delimiters": {
"left": "[",
"right": "]"
},
"filename": "Business Letter.docx",
"format": ".docx",
"region": "eu",
"page_count": 1,
"image_uri": "https://firebasestorage.googleapis.com/v0/b/storage.eu.docugenerate.com/o/templates%2FuVE30i1427KQsYcED0bl%2FBusiness%20Letter.png?alt=media&token=0ce64a4b-495a-426b-8783-42b479f7ae38",
"preview_uri": "https://firebasestorage.googleapis.com/v0/b/storage.eu.docugenerate.com/o/templates%2FuVE30i1427KQsYcED0bl%2FBusiness%20Letter.pdf?alt=media&token=0b3939c7-824e-4979-9aca-ca4a87175cbf",
"template_uri": "https://firebasestorage.googleapis.com/v0/b/storage.eu.docugenerate.com/o/templates%2FuVE30i1427KQsYcED0bl%2FBusiness%20Letter.docx?alt=media&token=d37a4458-3620-48db-94b8-6ac46f0442ab",
"id": "uVE30i1427KQsYcED0bl"
}
Bewahren Sie die id der Vorlage auf, da Sie sie zum Generieren von Dokumenten benötigen. Die folgenden optionalen Parameter können ebenfalls in data übergeben werden:
delimiters: Die Begrenzer zur Erkennung der Tags, als JSON-String gesendet, z. B. json.dumps({'left': '[', 'right': ']'}). Standardmäßig werden sie automatisch ermittelt.region: Wo die Vorlage und ihre generierten Dokumente gespeichert werden, entweder us, eu, uk oder au. Standardmäßig wird die Region des Kontos verwendet.enhanced_syntax: Auf 'true' setzen, um verschachtelte Eigenschaften und logische oder mathematische Operatoren in den Tags zu verwenden.versioning_enabled: Auf 'true' setzen, um beim Hochladen einer neuen Datei frühere Versionen zu behalten, sofern Ihr Plan dies erlaubt.folder: Der Ordner der Vorlage, von der Wurzel bis zur untersten Ebene. Fehlende Ordner werden automatisch erstellt.Um die Vorlage in einem Ordner abzulegen, übergeben Sie eine Liste mit einem Ordnernamen pro Ebene des Pfads, die requests als ein folder-Feld pro Ebene sendet. Zum Beispiel, um sie im Ordner Letters > Business abzulegen:
data={
'name': 'Business Letter',
'folder': ['Letters', 'Business']
}
Eine Anfrage an GET /template gibt alle Vorlagen in Ihrem Konto zurück:
response = requests.get(
f'{API_URL}/template',
headers={
'Authorization': API_KEY,
'Accept': 'application/json'
}
)
if not response.ok:
raise Exception(f'DocuGenerate API error {response.status_code}: {response.text}')
templates = response.json()
for template in templates:
print(template['id'], template['name'])
Um nur die Vorlagen eines Ordners aufzulisten, wiederholen Sie den Abfrageparameter folder für jede Ebene des Pfads. Eine Liste in params erledigt das automatisch. Zum Beispiel, um die Vorlagen im Ordner Letters > Business aufzulisten:
response = requests.get(
f'{API_URL}/template',
headers={
'Authorization': API_KEY,
'Accept': 'application/json'
},
params={'folder': ['Letters', 'Business']}
)
if not response.ok:
raise Exception(f'DocuGenerate API error {response.status_code}: {response.text}')
Es werden nur die Vorlagen zurückgegeben, die direkt in diesem Ordner liegen. Vorlagen in seinen Unterordnern sind nicht enthalten. Erfahren Sie mehr darüber, wie Sie mit der API Vorlagen in Ordnern organisieren.
Um eine einzelne Vorlage abzurufen, rufen Sie GET /template/{id} mit ihrer ID auf:
template_id = 'bet2oQirk0pSd9ctH9Qu'
response = requests.get(
f'{API_URL}/template/{template_id}',
headers={
'Authorization': API_KEY,
'Accept': 'application/json'
}
)
if not response.ok:
raise Exception(f'DocuGenerate API error {response.status_code}: {response.text}')
template = response.json()
print(template['tags']['valid'])
Das ist zum Beispiel nützlich, um vor dem Generieren von Dokumenten zu prüfen, welche Zusammenführungs-Tags die Vorlage erwartet.
Eine Anfrage an PUT /template/{id} aktualisiert eine Vorlage. Alle Parameter sind optional, senden Sie also nur die, die Sie ändern möchten. Zum Beispiel, um eine neue Version der Datei hochzuladen und die Vorlage umzubenennen:
template_id = 'bet2oQirk0pSd9ctH9Qu'
with open('Business Letter v2.docx', 'rb') as file:
response = requests.put(
f'{API_URL}/template/{template_id}',
headers={
'Authorization': API_KEY,
'Accept': 'application/json'
},
files={'file': file},
data={'name': 'Business Letter v2'}
)
if not response.ok:
raise Exception(f'DocuGenerate API error {response.status_code}: {response.text}')
template = response.json()
Wie beim Erstellen einer Vorlage muss der Body multipart/form-data sein, was zusammen mit der Multipart-Boundary automatisch gesetzt wird, wenn die Datei in files übergeben wird. Neben file und name können die folgenden optionalen Parameter in data übergeben werden:
delimiters: Die neuen Begrenzer, als JSON-String gesendet. Wenn sie angegeben werden, wird die Vorlage erneut analysiert, um die Zusammenführungs-Tags anhand der neuen Begrenzer zu erkennen. Wird ein neues file ohne delimiters hochgeladen, werden die aktuellen Begrenzer verwendet.region: Verschiebt die Vorlage in eine andere Region, entweder us, eu, uk oder au. Danach generierte Dokumente werden in der neuen Region gespeichert, während bestehende Dokumente in ihrer aktuellen Region bleiben.folder: Verschiebt die Vorlage in einen anderen Ordner, mit einem Ordnernamen für jede Ebene des Pfads. Senden Sie '[]', um die Vorlage aus jedem Ordner herauszunehmen.enhanced_syntax: Auf 'true' oder 'false' setzen, um die erweiterte Syntax zu aktivieren oder zu deaktivieren.versioning_enabled: Auf 'true' oder 'false' setzen, um den Versionsverlauf zu aktivieren oder zu deaktivieren, sofern Ihr Plan dies erlaubt.Um eine Vorlage zu löschen, senden Sie eine Anfrage an DELETE /template/{id}. Die API antwortet bei Erfolg mit dem Status 204 No Content:
template_id = 'bet2oQirk0pSd9ctH9Qu'
response = requests.delete(
f'{API_URL}/template/{template_id}',
headers={
'Authorization': API_KEY,
'Accept': 'application/json'
}
)
if not response.ok:
raise Exception(f'DocuGenerate API error {response.status_code}: {response.text}')
Sie generieren Dokumente mit einer Anfrage an POST /document, wobei Sie die template_id und die data übergeben, mit denen die Zusammenführungs-Tags ersetzt werden. Wenn der Body in json übergeben wird, setzt requests den Header Content-Type automatisch auf application/json:
response = requests.post(
f'{API_URL}/document',
headers={
'Authorization': API_KEY,
'Accept': 'application/json'
},
json={
'template_id': 'bet2oQirk0pSd9ctH9Qu',
'data': {
'Date': 'October 4, 2026',
'Name': 'Emily Carter',
'Job Title': 'Operations Manager',
'Company Name': 'Harbor Point Consulting',
'Street Address': '118 West Street',
'City': 'Annapolis',
'State': 'Maryland',
'Zip Code': '21405',
'Email': 'emily.carter@example.com',
'Phone': '(410) 555-0142'
},
'output_format': '.pdf'
}
)
if not response.ok:
raise Exception(f'DocuGenerate API error {response.status_code}: {response.text}')
document = response.json()
print(document['document_uri'])
Die Antwort enthält die Eigenschaften des Dokuments:
{
"created": 1791125416372,
"template_id": "bet2oQirk0pSd9ctH9Qu",
"name": "Business Letter",
"format": ".pdf",
"data_length": 1,
"filename": "Business Letter.pdf",
"document_uri": "https://firebasestorage.googleapis.com/v0/b/storage.us.docugenerate.com/o/documents%2FiESelthRt4uaYQRTemrL%2FBusiness%20Letter.pdf?alt=media&token=c4b259ec-249b-4b35-a62f-6a8dc0da75f3",
"id": "iESelthRt4uaYQRTemrL"
}
Das output_format kann .docx (Standard), .pdf, .doc, .odt, .txt, .html, .png oder eine PDF/A-Version sein. Sie können außerdem mit merge_with PDF-Dateien am Ende des generierten Dokuments zusammenführen oder mit attach Anhänge hinzufügen.
Datei herunterladen
Die document_uri verweist auf die generierte Datei, die Sie herunterladen und auf der Festplatte speichern können:
file = requests.get(document['document_uri'])
if not file.ok:
raise Exception(f'Download failed with status {file.status_code}')
with open(document['filename'], 'wb') as output:
output.write(file.content)
Datei direkt empfangen
Wenn das Dokument nicht in der Cloud gespeichert werden soll, setzen Sie den Header Accept auf application/octet-stream. Die API antwortet dann mit der Binärdatei statt mit JSON:
response = requests.post(
f'{API_URL}/document',
headers={
'Authorization': API_KEY,
'Accept': 'application/octet-stream'
},
json={
'template_id': 'bet2oQirk0pSd9ctH9Qu',
'data': {
'Date': 'October 4, 2026',
'Name': 'Emily Carter',
'Job Title': 'Operations Manager',
'Company Name': 'Harbor Point Consulting',
'Street Address': '118 West Street',
'City': 'Annapolis',
'State': 'Maryland',
'Zip Code': '21405',
'Email': 'emily.carter@example.com',
'Phone': '(410) 555-0142'
},
'output_format': '.pdf'
}
)
if not response.ok:
raise Exception(f'DocuGenerate API error {response.status_code}: {response.text}')
with open('Business Letter.pdf', 'wb') as output:
output.write(response.content)
print(response.headers['X-Document-Id'])
Batch-Dokumentgenerierung
Um mehrere Dokumente in einer Anfrage zu generieren, übergeben Sie eine Liste von Dictionaries als data. Für jedes Dictionary wird ein Dokument generiert:
response = requests.post(
f'{API_URL}/document',
headers={
'Authorization': API_KEY,
'Accept': 'application/json'
},
json={
'template_id': 'bet2oQirk0pSd9ctH9Qu',
'data': [
{'Date': 'October 4, 2026', 'Name': 'Emily Carter', 'Job Title': 'Operations Manager', 'Company Name': 'Harbor Point Consulting', 'Street Address': '118 West Street', 'City': 'Annapolis', 'State': 'Maryland', 'Zip Code': '21405', 'Email': 'emily.carter@example.com', 'Phone': '(410) 555-0142'},
{'Date': 'October 4, 2026', 'Name': 'Daniel Brooks', 'Job Title': 'Logistics Coordinator', 'Company Name': 'Northfield Logistics', 'Street Address': '2400 South Lamar Boulevard', 'City': 'Austin', 'State': 'Texas', 'Zip Code': '78704', 'Email': 'daniel.brooks@example.com', 'Phone': '(512) 555-0187'}
],
'output_format': '.pdf',
'single_file': True,
'page_break': True
}
)
if not response.ok:
raise Exception(f'DocuGenerate API error {response.status_code}: {response.text}')
document = response.json()
Standardmäßig werden alle Dokumente in einer einzigen Datei zusammengefasst, mit einem Seitenumbruch nach jedem Dokument. Setzen Sie page_break auf False, um die Seitenumbrüche zu entfernen.
Wenn single_file auf False gesetzt ist, wird pro Datenobjekt eine Datei generiert, und alle Dateien werden in einem .zip-Archiv zusammengefasst. Verwenden Sie den Parameter name, um das Archiv zu benennen, und output_name mit Zusammenführungs-Tags, um jeder Datei einen dynamischen Namen zu geben, z. B. Letter for [Name]:
json={
'template_id': 'bet2oQirk0pSd9ctH9Qu',
'data': [...],
'output_format': '.pdf',
'single_file': False,
'name': 'Business Letters',
'output_name': 'Letter for [Name]'
}
Dadurch entsteht ein Archiv Business Letters.zip mit Letter for Emily Carter.pdf und Letter for Daniel Brooks.pdf. Die Zusammenführungs-Tags in output_name müssen dieselben Begrenzer wie die Vorlage verwenden.
Datendatei verwenden
Um viele Dokumente auf einmal aus einer Excel- oder CSV-Datei zu generieren, senden Sie die Datei in einer multipart/form-data-Anfrage. Für jede Zeile der Tabelle wird ein Dokument generiert. Wenn die Datei mehrere Tabellenblätter enthält, geben Sie mit dem Parameter sheet an, welches verwendet werden soll.
with open('Data.xlsx', 'rb') as file:
response = requests.post(
f'{API_URL}/document',
headers={
'Authorization': API_KEY,
'Accept': 'application/json'
},
files={'file': file},
data={
'template_id': 'bet2oQirk0pSd9ctH9Qu',
'output_format': '.pdf'
}
)
if not response.ok:
raise Exception(f'DocuGenerate API error {response.status_code}: {response.text}')
Die Verwendung einer Datendatei ist eine weitere Form der Batch-Generierung, daher gelten dieselben Parameter, um die generierten Dokumente in einer einzigen Datei zusammenzufassen oder sie in einem .zip-Archiv mit einem eigenen Namen für jede Datei zu gruppieren.
Eine Anfrage an GET /document gibt die aus einer Vorlage generierten Dokumente zurück. Die ID der Vorlage wird im Abfrageparameter template_id übergeben:
response = requests.get(
f'{API_URL}/document',
headers={
'Authorization': API_KEY,
'Accept': 'application/json'
},
params={'template_id': 'bet2oQirk0pSd9ctH9Qu'}
)
if not response.ok:
raise Exception(f'DocuGenerate API error {response.status_code}: {response.text}')
documents = response.json()
for document in documents:
print(document['id'], document['name'], document['document_uri'])
Um ein einzelnes Dokument abzurufen, rufen Sie GET /document/{id} mit seiner ID auf:
document_id = 'iESelthRt4uaYQRTemrL'
response = requests.get(
f'{API_URL}/document/{document_id}',
headers={
'Authorization': API_KEY,
'Accept': 'application/json'
}
)
if not response.ok:
raise Exception(f'DocuGenerate API error {response.status_code}: {response.text}')
document = response.json()
Eine Anfrage an PUT /document/{id} benennt ein Dokument um, da der Name die einzige Eigenschaft ist, die geändert werden kann:
document_id = 'iESelthRt4uaYQRTemrL'
response = requests.put(
f'{API_URL}/document/{document_id}',
headers={
'Authorization': API_KEY,
'Accept': 'application/json'
},
json={'name': 'Letter for Emily Carter'}
)
if not response.ok:
raise Exception(f'DocuGenerate API error {response.status_code}: {response.text}')
document = response.json()
Um ein Dokument zu löschen, senden Sie eine Anfrage an DELETE /document/{id}. Die API antwortet bei Erfolg mit dem Status 204 No Content:
document_id = 'iESelthRt4uaYQRTemrL'
response = requests.delete(
f'{API_URL}/document/{document_id}',
headers={
'Authorization': API_KEY,
'Accept': 'application/json'
}
)
if not response.ok:
raise Exception(f'DocuGenerate API error {response.status_code}: {response.text}')